Mac Magazin/MacEasy 14

home *** CD-ROM | disk | FTP | other *** search

/ Mac Magazin/MacEasy 14 / Mac Magazin and MacEasy Magazine CD - Issue 14.iso / Wissenschaft & Technik / Tools Plus 2.6.1 Evaluation Kit / Tools Plus 2.6.1 / User Manual / 14-System Polling (4 of 4) < prev next >

Wrap

INI File | 1994-09-17 | 27KB | 590 lines

[Display using Monaco 9] doListBox (event) ````````````````` Indicator that user clicked or double-clicked in a list box. The doListBox event reports that the user has clicked somewhere in a list box (on a line that contains text or a blank line). This event is not generated when the user just scrolls the list box by using its scroll bar. Programming Considerations `````````````````````````` • If your application treats double-clicks in list boxes like clicking the OK button, use the GetListBoxLine function to determine which line was selected (or GetListBoxLines if multiple lines can be selected in the list box), then flash the OK button with the FlashButton procedure. • This event will never occur when the watch cursor is displayed, since list boxes cannot be clicked. • A doListBox event is not generated when the user clicks list boxes in a dialog box or desk accessory. These events are handled automatically. Valid Polling Record Fields ``````````````````````````` Poll.Window Poll.ListBox.Num Poll.ListBox.DoubleClick ------------------------------------------------------------------------ doClick (event) ``````````````` Indicator that the user has completed or in the midst of a click, double-click, triple-click, or drag. A click, double-click, triple-click, or drag has been reported in the active window. The event may still be in progress when PollSystem reports it, such as a double-click with the mouse button still down on the second click. The Mouse part of the event record contains a field called What, which is the mouse event code that tells your application what type of mouse click has occurred. The rest of the mouse record contains details on each mouse-down and mouse-up event. A series of decisions are made by PollSystem to obtain single and multiple-click information, as well as drags. Although they can be somewhat altered by your application (as explained later), the steps taken are as follows: 1 The first mouse-down of a click is in the active window’s content region, and is not in a button, picture button, scroll bar, editing field, list box, pop-up menu or custom control. 2 If no mouse-up event is in the queue, a “single-click, mouse still down” mouse event code is returned. If a mouse-up event is in the queue, it is used to complete the click. 3 If the time between the first mouse-down and the first mouse-up (single-click) is too long to be the first click of a multiple click, PollSystem returns with a “single-click completed” mouse event code. 4 If the time between the first mouse-down and the first mouse-up (single-click) is short enough to constitute the first click of a multiple click, PollSystem checks the event queue for a mouse-down event that would be the beginning of a second click. If a mouse- down event is not found in time, PollSystem returns with a “single- click completed” mouse event code. 5 If a second mouse-down event is in the queue, it must be in the active window’s content region, and must not be in a button, picture button, scroll bar, editing field, list box, pop-up menu or custom control. If any of these conditions are violated, the mouse-down event is left in the queue and PollSystem returns with a “single- click completed” mouse event code. If the conditions are not violated, PollSystem continues. 6 The second click has begun. If no mouse-up event is in the queue, a “double-click, mouse still down” mouse event code is returned. If a mouse-up event is in the queue, it is used to complete the click. 7 If the time between the second mouse-down and the second mouse-up (double-click) was too long to be the second click of a triple- click, PollSystem returns with a “double-click completed” mouse event code. 8 If the time between the second mouse-down and the second mouse-up (double-click) is short enough to constitute the second click of a triple-click, PollSystem checks the event queue for a mouse-down event that would be the beginning of a third click. If a mouse-down event is not found in time, PollSystem returns with a “double-click completed” mouse event code. 9 If a third mouse-down event is in the queue, it must be in the active window’s content region, and must not be in a button, picture button, scroll bar, editing field, list box, pop-up menu or custom control. If any of these conditions are violated, the mouse-down event is left in the queue and PollSystem returns with a “double- click completed” mouse event code. If the conditions are not violated, PollSystem continues. 10 The third click has begun. If no mouse-up event is in the queue, a “triple-click, mouse still down” mouse event code is returned. If a mouse-up event is in the queue, it is used to complete the click and return a “triple-click completed” mouse event code. Programming Considerations `````````````````````````` • If at some point your application is only concerned with a mouse down in a certain area, or a single-click only, or a double-click only, you can disrupt the click as soon as you have obtained enough information by using ResetMouseClicks. For example, if your application only cares about a single-click and it gets a “double-click, mouse still down” mouse event code, ResetMouseClicks will tell PollSystem “forget the rest of this click.” • A triple-click should be scrutinized by your application because the time between the third mouse-down and the third mouse-up may be longer than the allowable limit for consecutive clicks. This will also happen when the user double-clicks, then presses down the mouse button the third time and drags. Use the GetDblTime function to determine the maximum number of clock ticks which can occur between mouse-down and up events to constitute a consecutive click. • Your application can place cursor zones on a window, then use FindCursorZone to determine if a click occurred in one of those zones. This can make parts of your window, such as pictures or icons, click- sensitive. See “Cursors” for information about Cursor Tables and Cursor Zones. • This event will never occur when the watch cursor is displayed, since only buttons can be (optionally) clicked. • Poll.Event is populated with the mouse-down event (as obtained from the toolbox Event Manager) that is responsible for the doClick event. Some applications need this event to drive custom controls. • A doClick event is not generated when the user clicks in a desk accessory’s editing fields. The process is handled automatically. Valid Polling Record Fields ``````````````````````````` Poll.Window Poll.Mouse.What Poll.Mouse.Down[1].Where Poll.Mouse.Down[1].When Poll.Mouse.Down[1].Modifiers Poll.Event (for first mouse-down event only) The next three fields are valid only if the mouse event code is inClick1, inClick2Drag, inClick2, inClick3Drag, or inClick3. Poll.Mouse.Up[1].Where Poll.Mouse.Up[1].When Poll.Mouse.Up[1].Modifiers The next three fields are valid only if the mouse event code is inClick2Drag, inClick2, inClick3Drag, or inClick3. Poll.Mouse.Down[2].Where Poll.Mouse.Down[2].When Poll.Mouse.Down[2].Modifiers The next three fields are valid only if the mouse event code is inClick2, inClick3Drag, or inClick3. Poll.Mouse.Up[2].Where Poll.Mouse.Up[2].When Poll.Mouse.Up[2].Modifiers The next three fields are valid only if the mouse event code is inClick3Drag, or inClick3. Poll.Mouse.Down[3].Where Poll.Mouse.Down[3].When Poll.Mouse.Down[3].Modifiers The next three fields are valid only if the mouse event code is inClick3. Poll.Mouse.Up[3].Where Poll.Mouse.Up[3].When Poll.Mouse.Up[3].Modifiers Poll.Mouse.Where CONST {Mouse Event Codes } inClick1 = 1; {single-click completed } inClick2 = 2; {double-click completed } inClick3 = 3; {triple-click completed } inClick1Drag=-1; {single-click, mouse still down } inClick2Drag=-2; {double-click, mouse still down } inClick3Drag=-3; {tripple-click, mouse still down } Note: For C programmers… The polling record’s arrays are documented is using Pascal nomenclature (the elements are numbered 1, 2 and 3). In C, the same array’s elements are numbered 0, 1 and 2 (they start at zero). When C programmers read: Poll.Mouse.Down[1].Where it indicates the first element of the array, which translates to the following C source code: Poll.Mouse.Down[0].Where ------------------------------------------------------------------------ doPopUpMenu (event) ``````````````````` Indicator that the user selected a pop-up menu item. Programming Considerations `````````````````````````` • If your application determines that the item selected by the user should be checked, use CheckPopUp or PopUpMark to mark the item with a check mark or other special character. By default, the previously selected item is automatically unchecked (although you can override this behavior when creating the pop-up menu). • If your application determines that the selected pop-up menu item affects the active editing field, you may want to validate the field’s edited text before allowing the user to complete the action. If this is the case, use GetFieldString to obtain a copy of the edited text, then your application can check the string for errors. If an error is detected, display an appropriate alert box. If no error is detected, call the SaveFieldString procedure to save the edited text as the field’s string, then complete the menu’s action. • A doPopUpMenu event is not generated when the user selects desk accessory menus. These selections are handled automatically. Valid Polling Record Fields ``````````````````````````` Poll.Window Poll.Menu.Num Poll.Menu.Item Poll.Modifiers ------------------------------------------------------------------------ doPictButton (event) ```````````````````` Indicator that user has clicked a picture button, or is holding down a repeating picture button. The doPictButton event reports that the user has clicked a picture button in the active window. The doPictButton event is also reported if the user holds down a repeating picture button. Repeating picture button’s will produce events as long as: [1] the mouse button is held down, [2] the button does not reach the end of its range, and [3] the mouse pointer stays inside the picture button’s region. Programming Considerations `````````````````````````` • If the “automatic value change” option is not on, your application has to set the picture button’s value by using SetPictButtonVal or SetPictButtonValSelect. • If you have created a picture button that is “lock selected” with the “automatic value change” option off, and you’ve done this to validate the picture button before proceeding to the next stage, do the following: validate the button. If it can proceed to the next stage, use SetPictButtonValSelect to deselect the button and increment its value, otherwise use SetPictButtonValSelect to deselect the button and leave its value unchanged. • If the user clicked a picture button that is functioning like a radio button, use SelectPictButton to deselect the other picture buttons in the group. • This event will never occur when the watch cursor is displayed, since picture buttons cannot be clicked. The exception is if the WatchCursorButtons procedure has been used to allow the watch cursor to click picture buttons. • Picture buttons with the “repeating events” option turned on may produce doNothing events if your application calls PollSystem more frequently than the button changes its value. This will cause no ill side-effects, but you should be aware of this. • A doPictButton event is not generated when the user clicks picture buttons in another application, control panel or desk accessory. These events are handled automatically. • A negative button number value indicates that the decrementing half of a split button was clicked (i.e., “-5” indicates that button 5 is a split button, and its value is being decreased). Valid Polling Record Fields ``````````````````````````` Poll.Window Poll.Button.Num Poll.Modifiers ------------------------------------------------------------------------ doClickControl (event) `````````````````````` Indicator that user clicked a custom control. The doClickControl event reports that the user has clicked in a custom control. This event must be handled entirely by your application, since only you know how your custom control should behave. Programming Considerations `````````````````````````` • This event will never occur when the watch cursor is displayed, since custom controls cannot be clicked. Valid Polling Record Fields ``````````````````````````` Poll.Window Poll.Event Poll.Modifiers ------------------------------------------------------------------------ doManual (event) ```````````````` Indicator that an event has been reported that can’t be processed by Tools Plus. The doManualEvent event reports that some type of event has occurred which should be processed by your application. This includes seven (7) possible types of events as defined by the Toolbox Event Manager, which are listed below. If your application does not make use of any of these events, it can ignore the doManualEvent event code. diskEvt The Standard File Package takes care of all disk-inserted events, so applications using this package can ignore diskEvt events. If your application is unusual and it circumvents the Standard File package, your application will have to handle disk-inserted events itself. networkEvt Your application needs to respond to network events only if it is going to be communicating with the AppleTalk manager. If it is, you should read the appropriate documentation in chapter 10 Vol. 2 of Inside Macintosh regarding networks. driverEvt If your application does not intend to work with device drivers, it can ignore these events. Otherwise, you should read the appropriate documentation in Inside Macintosh regarding device drivers. app1Evt Application-defined events 1 through 4. These are events app2Evt whose meaning is defined by your application. If your app3Evt application does not define custom events, it can ignore app4Evt these event codes. Note that app4Evt (or osEvt) will osEvt only be reported if your application does not respond to Suspend/Resume events. See the SIZE resource for details. If your application does respond to Suspend/ Resume events, it will receive a doSuspend or doResume Tools Plus event. kHighLevel- Your application needs to respond to these events only if Evt you have defined the SIZE resource to respond to high- level events. See the SIZE resource for details. Valid Polling Record Fields `````````` Poll.Event ------------------------------------------------------------------------ doMoveWindow (event) ```````````````````` Indicator that user moved a window. The doMoveWindow event reports that the user has repositioned a window by dragging it by its title bar. Most applications will choose to ignore this event. Programming Considerations `````````````````````````` • The dragged window might not be the active window. The user can drag an inactive window by holding down the Command key before beginning the drag. • If part or all of a window is exposed by the drag and needs to be refreshed, a subsequent call to PollSystem will report a doRefresh event for this window. • Your application may call WindowStatus to obtain the window’s new location in the screen’s global co-ordinates. • This event will never occur when the watch cursor is displayed, since the title bar cannot be clicked. • A doMoveWindow event is not generated when the user drags a desk accessory. The process is handled automatically. Valid Polling Record Fields ``````````````````````````` Poll.Window ------------------------------------------------------------------------ doGrowWindow (event) ```````````````````` Indicator that user has changed a window’s size. The doGrowWindow event reports that the user has changed a window by dragging a window’s “size box.” This will always occur on the active window. Programming Considerations `````````````````````````` • Your application can call the WindowStatus procedure to obtain the window’s new width and height in pixels. • If the window is enlarged either vertically or horizontally, a subsequent call to PollSystem will report a doRefresh event for this window. • This event will never occur when the watch cursor is displayed, since the size box cannot be clicked. • A doGrowWindow event is not generated when the user changes a desk accessory’s size. The process is handled automatically. Valid Polling Record Fields ``````````````````````````` Poll.Window ------------------------------------------------------------------------ doClickDesk (event) ``````````````````` Indicator that user clicked in the desk top. The doClickDesk event reports that the user has clicked in the desk top. Most applications will choose to ignore this event, however, it can be used to deselect objects on the active window. Programming Considerations `````````````````````````` • This event will never occur when a modal window is active, since clicks cannot occur outside of the window. • This event will never occur when the watch cursor is displayed, since the desk top cannot be clicked. Valid Polling Record Fields ``````````````````````````` Poll.What ------------------------------------------------------------------------ doZoomWindow (event) ```````````````````` Indicator that user has changed a window’s size and/or location by zooming. The doZoomWindow event reports that the user has changed a window’s size and/or position by clicking the “zoom box.” This will always occur on the active window. Applications will typically ignore this event, or treat it similarly to the doGrowWindow event. Programming Considerations `````````````````````````` • Your application can call the WindowStatus procedure to obtain the window’s new width and height in pixels, as well as its new location in the screen’s global co-ordinates. • The window’s entire contents are erased during the zoom. A subsequent call to PollSystem will report a doRefresh event for this window. Responding to the doRefresh event will regenerate the window’s contents. • This event will never occur when the watch cursor is displayed, since the zoom box cannot be clicked. • A doZoomWindow event is not generated when the user click’s a desk accessory’s zoom box. The process is handled automatically. ------------------------------------------------------------------------ doSuspend (event) ````````````````` Indicator that your application is about to be suspended. The doSuspend event reports that your application will be suspended (or become a “background” application) the next time you call PollSystem. This occurs under MultiFinder or System 7 when a desk accessory or other application is launched, or when an inactive window belonging to a desk accessory or another application is activated. Programming Considerations `````````````````````````` • If your application is cutting, copying or pasting specialized objects (i.e. not text that is handled by editing fields), copy this material from your local scrap to the clipboard. ------------------------------------------------------------------------ doResume (event) ```````````````` Indicator that your application has been resumed. The doResume event reports that your application has become the active application. This occurs under MultiFinder or System 7 after your application has become suspended (see the doSuspend event). Programming Considerations `````````````````````````` • If your application is cutting, copying or pasting specialized objects (i.e. not text that is handled by text editing fields), you may want to check the clipboard to see if it contains the specialized objects that you can paste, then copy them to your local scrap. ------------------------------------------------------------------------ doChgInField (event) ```````````````````` Indicator that the contents of your application’s active editing field have been changed. The doChgInField event is reported whenever the active field in your application is altered, either through typing, cutting, pasting (including the use of the PasteIntoField routine), clearing, or undoing/redoing (using the Edit menu). Most applications will ignore this event. Valid Polling Record Fields ``````````````````````````` Poll.Window Poll.Field ------------------------------------------------------------------------ SetNullTime ``````````` Set the number of ticks (1/60 sec) your application can wait until it receives a doNothing event, and can perform one cycle of its background process. These settings affect only doNothing events. pascal void SetNullTime (long ForegroundTime; long BackgroundTime); procedure SetNullTime (ForegroundTime, BackgroundTime: longint); ForegroundTime is the amount of time (in 1/60 second “ticks”) your application can wait between receiving doNothing events when the application is the active application. You can specify a value from 0 (maximum background processing speed at the expense of other applications) to 15 (four cycles per second). BackgroundTime is the amount of time (in 1/60 second “ticks”) your application can wait between receiving doNothing events when the application is suspended (i.e. when another application is active under MultiFinder or System 7). By default, Tools Plus is initialized with ForegroundTime and BackgroundTime set to 0, meaning your application will have maximum performance at the expense of other applications and processes. Normally, applications that do background processing will set ForegroundTime to 1, and BackgroundTime to a higher value, thus slowing down the background processing when your application is suspended. If your application doesn’t do any background processing, use the maxNullTime constant to allow other applications and process the maximum utilization of the processor. Your application can change the values of ForegroundTime and BackgroundTime at any time. The change will take effect the next time that PollSystem is called. Also see: WaitAvail. CONST {Background process scheduling } maxNullTime = $7FFFFFFF; {Infinite time between doNothing events } ------------------------------------------------------------------------ WaitAvail ````````` Determine if the Macintosh running your application supports scheduled processing. This determines if SetNullTime’s settings will have any effect. pascal Boolean WaitAvail(void); function WaitAvail: BOOLEAN; This function returns a value of true if scheduled background processing is supported, or false if it is not. If the Macintosh running your application doesn’t support scheduled background processing, then SetNullTime’s settings will have no effect, and your application will receive a doNothing event each time it calls PollSystem when there are no events available. Internally, this routine reports if the WaitNextEvent trap is available to your application. ------------------------------------------------------------------------ ResetMouseClicks ```````````````` Discontinue a mouse’s “drag” or multiple clicks in progress. pascal void ResetMouseClicks(void); procedure ResetMouseClicks; The PollSystem function is used to detect single-clicks, double-clicks, and triple-clicks, as well as dragging which occurs between a mouse-down and mouse-up event. In some applications, it may suffice to know that the user pressed the mouse button with the cursor being within a specific region or cursor zone, without concern for the mouse button’s release. Or an application may allow a single-click only, thereby disallowing double or triple clicks. In such cases, the ResetMouseClicks procedure can be used to tell Tools Plus that sufficient mouse information has been retrieved, and to reset the click and drag mechanism. This reset will clear the current click or drag from PollSystem’s event queue. The next time the mouse button in pressed down, it will be considered to be a first mouse-down of either a single-click, double-click, triple-click, or drag. See PollSystem for details on how the system responds to mouse events. ------------------------------------------------------------------------ ApplicationSuspended ```````````````````` Determine if your application has been suspended (i.e. not the active application). pascal Boolean ApplicationSuspended(void); function ApplicationSuspended: BOOLEAN; This function returns a value of true if a desk accessory or another application is active under MultiFinder or System 7). A value of false is returned if your application is active, even though your application may not have any windows open. When running under MultiFinder or System 7, your application needs to have a SIZE resource with the “AcceptSuspendEvents” bit set to “1.” See the SIZE resource for details. ------------------------------------------------------------------------ “Field To Event” Cross reference ```````````````````````````````` The following table provides a quick cross reference between each field in the polling record, and which events make use of that field. Poll.Button doButton, doPictButton Poll.Event doClick (first mouse down only), doClickControl, doManualEvent, doResume, doSuspend Poll.Field doClickField, doChgInField Poll.Key… doKeyDown, doAutoKey, doKeyUp Poll.ListBox… doListBox Poll.Menu… doMenu, doPopUpMenu Poll.Modifiers doGoAway, doButton, doMenu, doKeyDown, doAutoKey, doKeyUp, doClickControl, doPopUpMenu, doPictButton Poll.Mouse… doClick Poll.ScrollBar… doScrollBar Poll.What (all) doNothing, doChgWindow, doRefresh, doGoAway, doButton, doMenu, doKeyDown, doAutoKey, doKeyUp, doClickField, doScrollBar, doListBox, doClick, doPopUpMenu, doPictButton, doClickControl, doManualEvent, doMoveWindow, doGrowWindow, doClickDesk, doZoomWindow, doSuspend, doResume, doChgInField Poll.Window doChgWindow, doRefresh, doGoAway, doButton, doKeyDown, doAutoKey, doKeyUp, doClickField, doScrollBar, doListBox, doClick, doPopUpMenu, doPictButton, doClickControl, doMoveWindow, doGrowWindow, doZoomWindow, doChgInField